home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d918.lha / MultiPlot / Plt / PLT_docs / PLT.doc < prev    next >
Text File  |  1993-10-04  |  15KB  |  348 lines
  1.                                 PLT:
  2.                              Version 1.3
  3.                           November 16, 1989
  4.  
  5.                            Rich Champeaux
  6.                              Jim Miller
  7.  
  8. NOTICE:  PLT: is not in the public domain.  We reserve all rights to both the
  9.          executable and the source.  PLT: is, however, freely distributable
  10.          as long as this file accompanies it and no profit is obtained from 
  11.          it's distribution.  Distribution in manners which violate the above 
  12.          restrictions are prohibited without the expressed, written permission
  13.          of either Rich Champeaux or Jim Miller.  The following services are 
  14.          granted permission to distribute PLT: without written permission:  
  15.          Fred Fish and Fish Disks, CompuServe, BIX, PeopleLink, and UseNet.
  16.  
  17.  
  18. PLT: is a file-handler that emulates a plotter by accepting HP-GL commands, 
  19. creating a raster image, and then dumping it to any Preferences supported 
  20. graphics printer.  The current resolution set with preferences is used, 
  21. allowing PLT: to make full use of a printer's capability.  
  22.  
  23. PLT: accepts virtually all of the standard HP-GL commands, including scaling
  24. and text.  The commands that were not implemented are those which are
  25. generally contained in an extended graphics cartridge, such as: circles, 
  26. arcs, filled regions, etc.
  27.  
  28.  
  29. PLT: Features:
  30.  
  31.    - Lines are stored in a tree/linked list structure untill the handler is
  32.      closed or the command AF or PG is recieved.  The plot is then rasterized
  33.      and dumped to the printer in strips.  This allows plots to be printed
  34.      with resolutions and page sizes for which a raster for the entire page
  35.      would not fit in memory.
  36.      
  37.    - Pens can be assigned colors and thicknesses.  The pen colors are defined
  38.      by RGB values, and thicknesses are defined in pixel widths.  The pens
  39.      can be defined in an environment variable or when the handler is opened.
  40.      The number of bit planes used for the raster depends on the number of
  41.      different colors requested, not the number of pens.  Therefore, 7 black
  42.      pens and 5 red pens of various thicknesses, would only take 2 bit planes.
  43.    
  44.    - PLT: supports variable paper sizes.  It knows the standard paper sizes,
  45.      A, B, C, D, and E, and can also use the paper size defined by the limits 
  46.      fields of Preference's Graphic 2 screen.  The entire width of any dot
  47.      matrix printer supported by Preferences can be used, including wide 
  48.      carriage printers.  If the requested page size is too large to be 
  49.      printed, a requester is displayed, giving the option to reduce the size
  50.      of the plot (keeping the aspect ratio) to the maximum size of the 
  51.      printer.  The plot can also be reduced to the page size specified by 
  52.      Preferences.
  53.      
  54.    - PLT: has a preview mode that displays the plot on the screen.  The 
  55.      aspect ratio of the requested page is preserved.  This allows the plot 
  56.      to be displayed on the screen the way it will appear on paper.  
  57.      A 640 x 400 screen is used to provide maximum resolution.
  58.      
  59.    - PLT: v1.3 supports multiple, disk-resident fonts.  The fonts can be 
  60.      changed or created by the user.  An included program, 'cf', is used to
  61.      convert the fonts from a text representation of the vectors to a
  62.      format usable by PLT:.  Fonts are loaded in only when needed, and 
  63.      fonts can be changed durring a plot with the CS, CA, SS, and SA HP-GL
  64.      commands.  A standard ascii font and a math-greek font are included
  65.      with this release.
  66.    
  67.    - PLT: can also be used by programs that assume that a plotter is 
  68.      connected to the serial port by using the CMD command.  For example:
  69.         CMD serial PLT:
  70.    
  71.    - PLT: has two memory usage modes that it can run in: memory-squander and
  72.      memory-conserve.  The memory-squander mode sits a tree structure on top
  73.      of the linked list to speed up inserts.  The memory-conserve mode uses
  74.      only a linked list.  The memory-squander mode is much faster than the
  75.      memory-conserve mode since it's insert time is O(log2(n)), but it 
  76.      requires twice as much memory per line.  The memory-conserve mode's 
  77.      insert time is O(n), and becomes unbearably slow as the number of lines
  78.      becomes greater than about 8000.  The memory-conserve mode does, however,
  79.      allow twice as many lines to be plotted.  PLT: v1.3 defaults to the 
  80.      memory-squander mode and will automatically remove the tree and switch to
  81.      the memory-conserve mode when availble memory is less than 2k.
  82.  
  83. -----------------------------------------------------------------------------
  84.  
  85. Installing PLT:
  86.  
  87.    1) Copy the file 'plt-handler' to the L: directory.
  88.    2) Create a directory and assign "PLTDATA:" to it.
  89.    3) copy the files 'ascii', 'math-greek', and 'pltfontnames' to the
  90.       directory 'PLTDATA:'
  91.    4) Add the following to the mountlist:
  92.    
  93.       PLT:        Handler   = L:plt-handler
  94.                   StartUp   = P/000-1
  95.                   StackSize = 5000
  96.                   Priority  = 5
  97.                   GlobVec   = 1
  98.       #
  99.       
  100.       
  101.       (Note: the StartUp field is used to pass default parameters to the
  102.        handler.  It is explained below.)
  103.        
  104.    5) Mount the handler using the command 'mount PLT:'
  105.    
  106. -----------------------------------------------------------------------------
  107.  
  108. Switches and Pen Definitions:
  109.  
  110.    PLT:'s mode switches and pen definitions are recieved from three sources:
  111. the mountlist entry, an environment variable, and the file name path.  All
  112. three sources use the following format:
  113.  
  114.       SWITCHES/RGB-t/RGB-t/RGB-t...
  115.  
  116.       where:
  117.          SWITCHES could be:  A..E  Selects standard page sizes A,B,C,D, or E.
  118.                                    (default is A)
  119.          
  120.                                 P  Selects the page size specified by the 
  121.                                    limits fields of Preferences' Graphics 2
  122.                                    screen.
  123.                                    
  124.                                 R  Reduces the plot (keeping the aspect ratio)
  125.                                    to the size specified by the limits fields
  126.                                    of Preferences' Graphics 2 screen.
  127.                                    
  128.                                 S  Draws plot on preview screen.
  129.                                 
  130.                                 W  Displays a status window when plotting to
  131.                                    printer. (default)
  132.                                    
  133.                                 M  Forces PLT: to use the memory-conserve
  134.                                    mode.
  135.                                  
  136.                                 L  Makes the label command do a carriage
  137.                                    return when it receives a line feed.
  138.                                    This switch allows copatability with the
  139.                                    Amiga since the newline character on the 
  140.                                    amiga is a linefeed.
  141.                                    
  142.                      (A '-' can be prefixed to a switch to negate it.)
  143.          
  144.          Pens are described as: RGB-t
  145.             where:
  146.                                 RGB is the color of the pen in hex.
  147.                                 t   is the pen thickness in pixels. (optional,
  148.                                     defaults to 1).
  149.                                     
  150.       Ex.
  151.          SB/000-1/f00-3/0c3-2
  152.          -WP/0f0/000-2/f30
  153.          /000-1/0f0-1/f00-2
  154.          DRM
  155.          C-R/000-1
  156.          
  157.    The switches and pen definitions defined in the mountlist or the 
  158. environment variable "pltinfo" are used as the defaults for PLT:.  If the
  159. environment variable exists, the entry in the mountlist is ignored.  These
  160. defaults can be temparily overridden by the switches and pen definitions
  161. passed to PLT: as the file path (Ex. PLT:SB/000-1/f00-2).  The switches
  162. specified with the file path selectively override the defaults.  For
  163. example, if the defaults were 'SBWR' and the switches specified in the file
  164. path were '-S-R' then the S and R switches would be negated, but the other
  165. switches would be unaffected.  Defining pens in the file path, however,
  166. completly replaces the default pen definitions.  A maximum of 15 pens can
  167. be defined.  If a pen is selected whose number is greater than the total
  168. number of defined pens, then the pen number is MODed with the total number
  169. of defined pens.
  170.  
  171.    To define the switches and pen definitions in the mountlist, use the field
  172. 'StartUp'.
  173.  
  174.    Ex.      StartUp = P/000-1/f00-1/0f0-1/00f-1
  175.    
  176. The StartUp field appears to be limited to 39 characters and cannot start 
  177. with a '-'.  If you require more characters or a leading '-', use the 
  178. environment variable.
  179.  
  180.    The enviroment variable used is "pltinfo".  It is set in the following
  181. manner:
  182.  
  183.    setenv pltinfo P/000-1/f00-1/0f0-1/00f-1
  184.    
  185. The enviroment variable has the advantage of being easily changed after PLT:
  186. has been mounted.
  187.  
  188. -----------------------------------------------------------------------------
  189.  
  190. Fonts:
  191.  
  192.    The fonts of PLT: are disk resident and user modifiable.  The fonts are
  193. stored in the directory PLTDATA:.  A file in that directory, 'pltfontnames',
  194. contains the names of the fonts accessible to PLT:.  The file contains a list
  195. of font names, one name per line, that are to be associated with the font
  196. numbers 0 thru 50.  The fonts are selected using the HP-GL character set
  197. commands: CS, CA, SS, SA.  CS and CA designate the standard and alternate
  198. fonts, respectively.  SS is then used to make the standard font the current
  199. font, and SA is used to make the alternate font the standard font.  The 
  200. default font is font 0, which is the first font listed in the file 
  201. 'pltfontnames'.
  202.  
  203.    The fonts are described by a text file, whose name ends with the extension
  204. '.fnt', and then must be compiled with the program 'cf' before they can be 
  205. used by PLT:.  The characters consist of 1 or more strokes of the pen.  Each 
  206. character in the font has an entry which specifies the value of the character 
  207. and a list of end points describing each stroke of the pen.
  208.  
  209.    The first 2 numbers in the file contain the width and height of the
  210. character cell.  Large characters, such as capital letters should completely
  211. fill the cell, however, the characters are allowed to have end points that
  212. lie outside of the cell.
  213.  
  214.    The first line of each character entry consists of an '*' followed by the
  215. value of the character.  The remaining part of the line is a comment.  
  216. Following that are the pen strokes that make up the character.  Each stroke
  217. consists of a number indicating the number of end points in the stroke,
  218. followed by the the starting location of the stroke, followed by the end
  219. points of the lines in the stroke.  Below is an example of a character entry.
  220. The comments on the right are only for the documentation and should not be
  221. in the actual font file.
  222.  
  223.  
  224. *  48 '0'      Below are comments that should not be in the actual file
  225. 8              <- number of end points (lines) in the first stroke.
  226. 12 3           <- starting point of the first stroke
  227. 12 18          <- end point of the first line in the stroke
  228. 9 21           <-|
  229. 3 21           <-|
  230. 0 18           <-|
  231. 0 3            <-|- more end points
  232. 3 0            <-|
  233. 9 0            <-|
  234. 12 3           <-|
  235. 1              <- number of end points (lines) in the next stroke
  236. 10 20          <- starting point of next stroke
  237. 2 1            <- end point of the only line in the second stroke
  238.  
  239.    The character entry is ended by the occurance of the '*' marking the next
  240. character entry.
  241.  
  242.    The font file is compiled and placed in the PLTDATA: directory by the 
  243. program 'cf'.
  244.  
  245.    Ex.   cf ascii
  246.  
  247. The font file is assumed to end with the extension '.fnt'.
  248.  
  249.    The cf program is only a simple state machine, so it does not handle errors
  250. very well.  It merely tells you what the character it discovered the error at
  251. was and the position of that character in the file.  Source to the cf program
  252. is included with this release.
  253.  
  254. -----------------------------------------------------------------------------
  255.  
  256. Specifing the Raster Height:
  257.  
  258.    The maximum height of the raster that PLT: uses when it prints a strip of
  259. the plot can be specified by the user.  The user specifies the maximum number
  260. of lines in the raster using the enviroment variable 'PltMaxRasHgt'.
  261.  
  262.    Ex.   setenv PltMaxRasHgt 100
  263.    
  264.    Specifing the maximum raster height is a way of controlling the amount of
  265. memory that PLT: uses for the raster.  The actual raster height that is used
  266. is always a multiple of the number of lines that the printer driver can print
  267. in one "strip" at the specified resolution.  The minimum raster height, and 
  268. the default, is the height of one "strip".
  269.  
  270. -----------------------------------------------------------------------------
  271.  
  272. Specifing the Left Margin:
  273.  
  274.    The left margin of the plot can be specified in inches using the environment
  275. variable 'PltXOffset'.  
  276.  
  277.    Ex.   setenv PltXOffset 0.5
  278.    
  279.    The value is only accurate to one tenth of an inch.
  280.  
  281. -----------------------------------------------------------------------------
  282.  
  283. Operation:
  284.  
  285. PLT: can be used in a variety of manners. 
  286.  
  287. 1.      You can copy files containing HP-GL commands to the handler.
  288.             Ex.  copy <filename> PLT:
  289.         
  290. 2.      You can direct a CAD package to plot to a file and give the 
  291.         filaname as "PLT:"
  292.         
  293. 3.      You can redirect output from a CAD package heading towards
  294.         the serial port to the handler.
  295.             Ex.  cmd serial.device PLT:
  296.         
  297. 4.      You can write your own applications that write directly to the
  298.         handler PLT:.
  299.             Ex.   file=fopen("PLT:","w");
  300.  
  301. -----------------------------------------------------------------------------
  302.  
  303. Memory:
  304.  
  305. PLT: does take up quite a bit of memory.  Not as much as a full raster image,
  306. but still quite alot.
  307.  
  308. PLT: code needs      35K
  309. printer.device needs 49K
  310. raster varies from    5K - 14K
  311. each lines takes     28 bytes  (or 16 in the Memory Conserve mode)
  312.  
  313.  
  314. Before data is read, PLT: removes about 90K - 100K from your system.
  315.  
  316. An average plot will usually require an additional 30-50k.
  317. A complex plot will usually require about 180K or more.
  318.  
  319. -----------------------------------------------------------------------------
  320.  
  321.  
  322. QUESTIONS or BUG REPORTS
  323.  
  324.    Since there have been so many changes to PLT: from v1.2, there are sure to
  325. be numerous bugs lurking in the code.  Any questions or bug reports should be
  326. sent to the following addresses:
  327.  
  328. Rich Champeaux
  329. rchampe@hubcap.clemson.edu
  330.  
  331. or
  332.  
  333. Jim Miller
  334. jvmiller@rdrc.rpi.edu
  335.  
  336. or send US mail to: 
  337.  
  338. Rich Champeaux
  339. 11 Mansfield Dr.
  340. Chelmsford, MA  01824
  341.  
  342. (Sending US mail to the above address will be slow, since that is my home
  343.  address, not my school address)
  344.  
  345.    Every attempt will be made to solve your problems within a reasonable 
  346. amount of time.
  347.  
  348.